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1 . INTRODUCTION. 

This manual describes CP/M, release 2, system organization 
including the structure of memory and system entry points. The 
intention is to provide the necessary information required to write 
programs which operate under CP/M, and which use the peripheral and 
disk I/O facilities of the system. 

CP/M is logically divided into four parts, called the Basic I/O 
System (BIOS) , the Basic Disk Operating System (BDOS) , the Console 
command processor (CCP) , and the Transient Program Area (TPA) . The 
BIOS is a hardware-dependent module which defines the exact low level 
interface to a particular computer system which is necessary for 
peripheral device I/O. 

Digital Research, explicit instructions 
reconfiguration of the BIOS to match nearly anv hardware 
(see the Digital Research manual entitled juiae ; . 

The BIOS and BDOS are logically combined into a single module with a 
common entry point, and referred to as the FDOS. The CCP is a 
distinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the backup storage 
device. The TPA is an area of memory (i.e., the portion which is not 
used by the FDOS and CCP) where various non-resident operating system 
commands and user programs are executed. The lower portion of memory 
is reserved for system information and is detailed later sections. 
Memory organization of the CP/M system in shown below: 


high 

memory 

FBASE: 

CBASE: 

TBASE: 

BOOT: 


FDOS (BDOS+BIOS) 


CCP 


TPA 


system parameters 


The exact memory addresses corresponding to BOOT, TBASE, CBASE, and 
FBASE vary from version to version, and are described fully in the 
“CP/M Alteration Guide." All standard CP/M versions, however, assume 
BOOT ■ 0000H, which is the base of random access memory. The machine 
code found at location BOOT performs a system “warm start" which loads 
and initializes the programs and variables necessary to return control 
to the CCP. Thus, transient programs need only jump to location BOOT 
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to return control to CP/M at the command level. Further, the standard 
versions assume TBASE = BOOT+0100H which is normally location 0100H, 
The principal entry point to the FDOS is at location BOOT+0005H 
(normally 0005H) where a jump to FBASE is found. The address field at 
BOOT+0 006H (normally 0006H) ' contains the value of FBASE and can be 
used to determine the size of available memory, assuming the CCP is 
being overlayed by a transient program. 

Transient programs are loaded into the TPA and executed as 
follows. The operator communicates with the CCP by typing command 
lines following each prompt. Each command line takes one of the 
forms? 


command 
command filel 
command filel f ile2 

where "command" is either a built-in function such as DIR or TYPE, or 
the name of a transient command or program. If the command is a 
built-in function of CP/M, it is executed immediately. Otherwise, the 
CCP searches the currently addressed disk for a file by the name 

command. COM 

If the file is found, it is assumed to be a memory image of a program 
which executes in the TPA, and thus implicitly originates at TBASE in 
memory. The CCP loads the COM file from the disk into memory starting 
at TBASE and possibly extending up to CBASE. 

If the command is followed by one or two file specifications, 
the CCP prepares one or two file control block (FCB) names in the 
system parameter area. These optional FCB's are in the form necessary 
to access files through the FDOS, and are described in the next 
section. 

The transient program receives control from the CCP and begins 

execution, perhaps using the I/O. facilities of the FDOS, The 

transient program is “called" from the CCP, and thus can simply return 
to the CCP upon completion of its processing, or can jump to BOOT to 
pass control back to CP/M. In the first case, the transient program 

must not use memory above CBASE, while in the latter case, memory up 

through FBASE- 1 is free. 

The transient program may use the CP/M I/O facilities to 
communicate with the operator's console and peripheral devices, 
including the disk subsystem. The I/O system is accessed by passing a 
"function number" and an "information address" to CP/M through the 
FDOS entry point at BOOT+0005H. In the case of a disk read, for 
example, the transient program sends the number corresponding to a 
disk read, along with the address of an FCB to the CP/M FDOS. The 
FDOS, in turn, performs the operation and returns with either a disk 
read completion indication or an error number indicating that the disk 
read was unsuccessful. The function numbers and error indicators are 
given in bela*. 
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2. OPERATING SYSTEM CALL CONVENTIONS. 

The purpose of this section is to provide detailed information 
for performing direct operating system calls from user programs. Many 
of the functions listed below, however, are more simply accessed 
through the I/O macro library provided with the MAC macro assembler, 
and listed in the Digital Research manual entitled "MAC Macro 
Assembler: Language Manual and Applications Guide." 

CP/M facilities which are available for access by transient 
programs fall into two general categories: simple device I/O, and 
disk file I/O. The simple device operations include: 

Read a Console Character 
Write a Console Character 
Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 
Print Console Buffer 
Read Console Buffer 
Interrogate Console Ready 

The FDOS operations which perform disk Input/Output are 

Disk System Reset 
Drive Selection 
File Creation 
File Open 
File Close 
Directory Search 
File Delete 
File Rename 

Random or Sequential Read 
Random or Sequential Write 
Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 
Set/Reset File Indicators 

As mentioned above, access to the FDOS functions is accomplished 
by passing a function number and information address through the 
primary entry point at location BOOT+0005H. In general, the function 
number is passed in register C with the information address in the 
double byte pair DE. Single byte values are returned in register A, 
with double byte values returned in HL (a zero value is returned when 
the function number is out of range). For reasons of compatibility, 
register A = L and register B = H upon return in all cases. Note that 
the register .passing conventions of CP/M agree with those of Intel’s- 
PL/M systems programming language. The list of CP/M function numbers 
is given below. 
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0 System Reset 

1 Console Input 

2 Console Output 

3 Reader Input 

4 Punch Output 

5 List Output 

6 Direct Console I/O 

7 Get I/O Byte 

8 . Set I/O Byte 

9 Print String 

10 Read Console Buffer 

11 Get Console Status 

12 Return Version Number 

13 Reset Disk System 

14 Select Disk 

15 Open File 

16 Close File 

17 Search for First 

18 Search for Next 


19 Delete File 

20 Read Sequential 

21 Write Sequential 

22 Make File 

23 Rename File 

24 Return Login Vector 

25 Return Current Disk 

26 Set DMA Address 

27 Get Addr (Alloc) 

28 Write Protect Disk 

29 Get R/O Vector 

30 Set File Attributes 

31 Get Addr (Disk Parms ) 

32 Set/Get User Code 

33 Read Random 

34 Write Random 

35 Compute File Size 

36 Set Random Record 


(Functions 28 and 32 should be avoided in application 
maintain upward compatibility with MP/M.) 


programs 


to 


Upon entry to a transient program, the CCP leaves the stack 
pointer set to an eight level stack area with the CCP return address 
pushed onto the stack, leaving seven levels before overflow occurs. 
Although this stack is usually not used by a transient program (i.e., 
most transients return to the CCP though a jump to location 0000H) , it 
is sufficiently large to make CP/M system calls since the FDOS 
switcnes to a local stack at system entry. The following assembly 
language program segment, for example, reads characters continuously 
until an asterisk is encountered, at which time control returns to the 
CCP (assuming a standard CP/M system with BOOT = 0000H) ; 


BDOS 

EQU 

0005H 

CONIN 

EQU 

1 

t 

OPG 

0 1 0 0H 

NEXTC : 

MVI 

C, CONIN 


CALL 

BDOS 


CPI 

• * • 


JNZ 

NEXTC 


RET 



END 



STANDARD CP/M ENTRY 
CONSOLE INPUT FUNCTION 

BASE OF TPA 
READ NEXT CHARACTER 
RETURN CHARACTER IN <A> 
END OF PROCESSING? 

LOOP IF NOT 
RETURN TO CCP 


CP/M implements a named file structure on each disk, providing a 
logical organization which allows any particular file to contain any 
number of records from completely empty, to the full capacity of the 
drive. Each drive is logically distinct with a disk directory and 
file data area. The disk file names are in three parts; the drive 
select code, the file name consisting of one to eight non-blank 
characters, and the file type consisting of zero to three non-blank 
characters. The file type names the generic category of a particular 
file, while the file name distinguishes individual files in each 
category. The file types listed below name a few generic categories 
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which have been established, although they are generally arbitrary: 


ASM 

Assembler Source 

PLI 

PRN 

Printer Listing 

REL 

HEX 

Hex Machine Code 

TEX 

BAS 

Basic Source File 

BAK 

INT 

Intermediate Code 

SYM 

COM 

CCP Command File 

$$$ 


PL/I Source File 
Relocatable Module 
TEX Formatter Source 
ED Source Backup 
SID Symbol File 
Temporary File 


Source files are treated as a sequence of ASCII characters, where each 
"line” of the source file is followed by a carriage-return line-feed 
sequence ( 0DH followed by 0AH) . Thus one 128 byte CP/M record could 
contain several lines of source text. The end of an ASCII file is 
denoted by a control-Z character ( 1AH) or a real end of file, returned 
by the CP/M read operation. Control-Z characters embedded within 
machine code files (e.g., COM files) are ignored, however, and the end 
of file condition returned by CP/M is used to terminate read 
operations. 


Files in CP/M can be thought of as a sequence of up to 65536 
records of 128 bytes each, numbered from 0 through 65535, thus 
allowing a maximum of 8 megabytes per file. Note, however, that 
although the records may be considered logically contiguous, they may 
not be physically contiguous in the disk data area. Internally, all 
files are broken into 16K byte segments called logical extents, so 
that counters are easily maintained as 8-bit values. Although the 
decomposition into extents is discussed in the paragraphs which 
follow, they are of no particular consequence to the programmer since 
each extent is automatically accessed in both sequential and random 
access modes. 

% 

In the file operations starting with function number 15, DE 
usually addresses a file control block (FCB) . Transient programs 
often use the default file control block area reserved by CP/M at 
location BOOT+005CH (normally 005CH) for simple file operations. The 
basic unit of file information is a 128 byte record used for all file 
operations, thus a de'fault location for disk I/O is provided by CP/M 
at location BOOT+0080H (normally 0080H) which is the initial default 
DMA address (see function 26) . All directory operations take place in 
a reserved area which does not affect write buffers as was the case in 
release 1, with the exception of Search First and Search Next, where 
compatibility is required. 

The File Control Block (FCB) data area consists of a sequence of 
33 bytes for sequential access and a series of 36 bytes in the case 
that the file is accessed randomly. The default file control block 
normally located at 005CH can be used for random access files, since 
the three bytes starting at BOOT+007DH are available for this purpose. 
The FCB format is shown with the following fields: 
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|dr I £1 1 £2 I / / | £8 1 tl 1 12 1 13 I ex| si I s2 1 rc |d0 I / / I dn I cr I r 0 I rl ! r 2 I 


00 01 02 ... 08 09 10 11 12 13 14 15 16 ... 31 32 33 34 35 
where 

dr drive code (0 - 16) 

0 -> use default drive for file 

1 -> auto dis.k select drive A, 

2 -> auto disk select drive B , 

• e o 

1 6-> auto disk select drive P. 

fl...f8 contain the file name in ASCII 
upper case, with high bit - 0 


tl,t2,t3 contain the file type in ASCII 
upper case, with high bit = 0 
tl 8 , t2', and t3' denote the 
bit of these positions, 
tl" - 1 -> Read/Only file, 
t2 8 - 1 => SYS file, no DIR list 


ex contains the current extent number, 

normally set to 00 by the user, but 
in range 0-31 during file I/O 

si reserved for internal system use 

s2 reserved for internal system use, set 

to zero on call to OPEN, MAKE, SEARCH 

rc record count for extent “ex,' 8 

takes on values from 0 - 128 

d0...dn filled-in by CP/M, reserved for 
system use 

cr current record to read or write in 

a sequential file operation, normally 
set to zero by user 


r0,rl,r2 optional randcm record number in the 
range 0-65535, with overflow to r2, 
r0,rl constitute a 16-bit value with 
low byte r0, and high byte rl 


Each file being accessed through CP/M must have a corresponding 
FCB which provides the name and allocation information for all 
subsequent file operations. When accessing files, it is the 
programmer's responsibility to fill the lower sixteen bytes of the FCB 
and initialize the "cr" field. Normally, bytes 1 through 11 are set 
to the ASCII character values for the file name and file type, while 
all other fields are zero. 
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FCB's are stored in a directory area of the disk, and are 
brought into central memory before proceeding with file operations 
(see the OPEN and MAKE functions). The memory copy of the FCB is 
updated as file operations take place and later recorded permanently 
on disk at the termination of the file operation (see the CLOSE 
command) . 

The CCP constructs the first sixteen bytes of two optional FCB's 
for a transient by scanning the remainder of the line following the 
transient name, denoted by "filel" and '“file2'' in the prototype 
command line described above, with unspecified fields set to ASCII 
blanks. The first FCB is constructed at location BOOT+005CH, and can 
be used as-is for subsequent file operations. The second FCB occupies 
the d0 ... dn portion of the first FCB, and must be moved to another 
area of memory before use. If, for example, the operator types 

PROGNAME B :X. ZOT Y.ZAP 

the file PROGNAME.COM is loaded into the TPA , and the default FCB at 
BOOT+005CH is initialized to drive code 2, file name "X" and file type 
"ZOT". The second drive code takes the default value 0, which is 
placed at BOOT+006CH, with the file name "Y" placed into location 
BOOT+006DH and file type "ZAP" located 8 bytes later at BOOT+0075H. 
All remaining fields through “cr" are set to zero. Note again that it 
is the programmer's responsibility to move this second file name and 
type to another area, usually a separate file control block, before 
opening the file which begins at BOCT+005CH, due to the fact that the 
open operation will overwrite the second name and type. 

If no file names are specified in the original command, then the 
fields beginning at BOOT+005DH and BOOT+006DH contain blanks. In all 
cases, the CCP translates lower case alphabetics to upper case to be 
consistent with the CP/M file naming conventions. 

As an added convenience, the default buffer area at location 
BOOT+0080H is initialized to the command line tail typed by the 
operator following the program name. The first position contains the 
number of characters, with the characters themselves following the 
character count. Given the above command line, the area beginning at 
BOOT+0080H is initialized as follows: 

BOOT+0080H: 

+00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14 

so is iegH IS 0 80 »a 00 M 88 M 2 •• ,e Q 00 06 99 49 •• 80 Y H 10 00 ,0 2 81 ** A M 89 P 69 

where the characters are translated to upper case ASCII with 
uninitialized memory following the last valid character. Again, it is 
the responsibility of the programmer to extract the information from 
this buffer before any file operations are performed, unless the 
default DMA address is explicitly changed. 

The individual functions are described in detail in the pages 
which follow. 
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*************************************** 
* * 

* FUNCTION 0: System Reset * 

* . * 

*************************************** 

* Entry Parameters? * 

* Register Cs 00H * 

*************************************** 



The system reset function returns control to the CP/M operating 
system at the CCP level. The CCP re-inifeializes the disk subsystem by 
selecting and logging-in disk drive A. This function has exactly the 
same effect as a jump to location BOOT. 




* FUNCTION 1: CONSOLE INPUT * 

* * 
*************************************** 


* 

Entry Parameters: 

* 

* 

* 

Register C: 

0 1H * 

* 

* 

Returned Value: 

■ * 

* 

Register A: 

ASCII Character * 


*************************************** 


The console input function reads the next console character to 
register A. Graphic characters, along with carriage return, line 
feed, and backspace (ctl-H) are echoed to the console. Tab characters 
(ctl-I) are expanded in columns of eight characters. A check is made 
for start/stop scroll (ctl-S) and start/stop printer echo (ctl-P) . 
The FDOS does not return to the calling program until a character has 
been typed, thus suspending execution if a character is not ready. 


**************************************** 

* * 

* FUNCTION 2 : CONSOLE OUTPUT * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 02H * 

* Register E: ASCII Character * 

* * 

*************************************** 

The ASCII character from register E is sent to the console 
device. Similar to function 1, tabs are expanded and checks are made 
for start/stop scroll and printer echo. 
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*************************************** 
* * 

* FUNCTION 3: READER INPUT * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 03H * 

* * 

* Returned Value: * 

* Register A: ASCII Character * 
*************************************** 


The Reader Input function reads the next character from the 
logical reader into register A (see the IOBYTE definition in the "CP/M 
Alteration Guide"). Control does not return until the character has 
been read. 


*************************************** 

* * 

* FUNCTION 4: PUNCH OUTPUT * 

★ * 

*************************************** 

* Entry Parameters: * 

* Register C: 04H * 

* Register E: ASCII Character * 

* * 
*************************************** 

The Punch Output function sends the character from register E to 
the logical punch device. 


*************************************** 
* * 

* FUNCTION 5: LIST OUTPUT * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 05H * 

* Register E: ASCII Character * 

* * 

a*******************#********'* *★★***#** 


The List Output function sends the ASCII character in register E 
to the logical listing device. 
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*************************************** 
* * 


* FUNCTION 6: DIRECT CONSOLE I/O * 

* * 

*************************************** 


* 

Entry Parameters; 


* 

* 

Register C; 

06H 

* 

* 

Register E; 

0FFH (input) or 

* 

* 

* 

char, (output) 

* 

* 

* 

Returned Value; 


* 

* 

Register A; 

char or status 

* 


(no value) 

* 


*************************************** 


Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is required. 
Use of this function should, in general, be avoided since it bypasses 
all of CP/M 8 s normal control character functions (e.g. , control-S and 
control”?) . Programs which perform direct I/O through the BIOS under 
previous releases of CP/M, however, should be changed to use direct 
I/O under BDOS so that they can be fully supported under future 
releases of MP/M and CP/M. 

Upon entry to function 6, register E either contains hexadecimal 
FF , denoting a console input request, or register E contains an ASCII 
character. If the input value is FF, then function 6 returns A = 00 
if no character is ready, otherwise A contains the next console input 
character. 

If the input value in E is not FF, then function 6 assumes that 
E contains a valid ASCII character which is sent to the console. 
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* FUNCTION 7: GET I/O BYTE * 

★ * 

*************************************** 

* Entry Parameters: * 

* Register C: 07H * 

* * 

* Returned Value: * 

* Register A: I/O Byte Value * 
*************************************** 


The Get I/O Byte function returns the current value of IOBYTE in 
register A. See the "CP/M Alteration Guide" for IOBYTE definition. 




* FUNCTION 8: SET I/O BYTE * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 08H * 

* Register E: I/O Byte Value * 

* * 

*************************************** 


The Set I/O Byte function changes the system IOBYTE value to 
that given in register E. 


*************************************** 


* FUNCTION 9: PRINT STRING 


*************************************** 

* Entry Parameters: - * 

* Register C: 09H * 

* Registers DE: String Address * 

* * 

*************************************** 


The Print String function sends the character string stored in 
memory at the location given by DE to the console device, until a 
is encountered in the string. Tabs are expanded as in function 2, and 
checks are made for start/stop scroll and printer echo. 
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* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 

* 


************************************** 

* 

FUNCTION 10: READ CONSOLE BUFFER * 

* 

****************3t£* ***************** 

Entry Parameters: * 

Register Cs 0AH * 

Registers DE: Buffer Address * 

* 

Returned Value: * 

Console Characters in Buffer * 
************************************** 


The Read Buffer function reads a line of edited console input 
into a buffer addressed by registers DE. Console input is terminated 
when either the input buffer overflows. The Read Buffer takes the 
form: 

DE: +0 +1 +2 +3 +4 +5 +6+7+8 ... +n 


Imx!nc|cl|c2|c3!c4!c5ic6|c7| . . . |??| 


where "mx" is the maximum number of characters which the buffer will 
hold (1 to 255) , "nc“ is the number of characters read (set by FDOS 
upon return), followed by the characters read from the console. if nc 
< rax, then uninitialized positions follow the last character, denoted 
by "??'• in the above figure. A number of control functions are 
recognized during line editing: 

rub/del removes and echoes the last character 
ctl-C reboots when at the beginning of line 
ctl-E causes physical end of line 
ctl-H backspaces one character position 
ctl-J (line feed) terminates input line 
ctl-M (return) terminates input line 
etl-R retypes the current line after new line 
ctl-U removes currnt line after new line 
ctl-x backspaces to beginning of current line 

Note also that certain functions which return the carriage to the 
leftmost position (e.g., ctl-X) do so only to the column position 
where the prompt ended (in earlier releases, the carriage returned to 

extreme left margin). This convention makes operator data incut 
and line correction more legible. 
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*************************************** 

* * 

* FUNCTION 11: GET CONSOLE STATUS * 

* * 
*************************************** 

* Entry Parameters: * 

* Register C: 0BH * 

* * 

* Returned Value: * 

* Register A: Console Status * 
*************************************** 

The Console Status function checks to see if a character has 
been typed at the console. If a character is ready, the value 0FFH is 
returned in register A. Otherwise a 00H value is returned. 


*************************************** 

* * 

* FUNCTION 12: RETURN VERSION NUMBER * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 0CH * 

* * 

* Returned Value: * 

* Registers HL: Version Number * 
*************************************** 

Function 12 provides information which ^ allows version 
independent programming. A two— byte value is returned, with H = 00 

designating the CP/M release (H — 01 for MP/M) , and L = 00 for all 
releases previous to 2.0. CP/M 2.0 returns a hexadecimal 20 in 
register L, with subsequent version 2 releases in the hexadecimal 

range 21, 22, through 2F. Using function 12, for example, you can 
write application programs which provide both sequential and random 
access functions, with "random access disabled when operating under 
early releases of CP/M. 
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*************************************** 


* * 

* FUNCTION 13; RESET DISK SYSTEM * 

* if 
*************************************** 

* Entry Parameters; * 

* Register C; 0DH * 

* * 

***********************************^^*^ 


The Reset Disk Function is used to programmatically restore the 
file system to a reset state where all disks are set to read/write 
(see functions 28 and 29) , only disk drive A is selected, and the 
default DMA address is reset to BOOT+0080H. This function can be 
used, for example, by an application program which requires a disk 
change without a system reboot. 



I 




i 




* 

• 


* 

* 

FUNCTION 14; SELECT DISK 

* 

* 



* 

*************************************** 

* 

Entry Parameters; 


* 

* 

Register C; 

0EH 

* 

* 

* 

Register E: 

Selected Disk 

* 

* 




The Select Disk function designates the disk drive named in 
register E as the default disk for subsequent file operations, with E 
38 0 for drive A, 1 for drive B, and so-£orth through 15 corresponding 
to drive P in a full sixteen drive system. The drive is placed in an 
“on-line*” status which, in particular, activates its directory until 
the next cold start, warm start, or disk system reset operation. If 
the disk media is changed while it is on-line, the drive automatically 
goes to a read/only status in a standard CP/M environment (see 
function 28). FCB*s which specify drive code zero (dr = 00H) 
automatically reference the currently selected default drive. Drive 
code values between 1 and 16, however, ignore the selected default 
drive and directly reference drives A through P. 
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*************************************** 
* * 

* FUNCTION 15: OPEN FILE * 

* * 




* Entry Parameters: 

* Register C: 0FH 

* Registers DE: FCB Address 

* 


* 

★ 

* 

* 


* Returned Value: * 

* Register A: Directory Code * 
*************************************** 


The Open File operation is used to activate a file which 
currently exists in the disk directory for the currently active user 
number. The FDOS scans the referenced disk directory for a match in 
positions 1 through 14 of the FCB referenced by DE (byte si is 
automatically zeroed) , where an ASCII question mark (3FH) matches any 
directory character in any of these positions. Normally, no question 
marks are included and, further, bytes "ex" and "s2" of the FCB are 
zero. 


If a directory element is matched, the relevant directory 
information is copied into bytes d0 through dn of the FCB, thus 
allowing access to the files through subsequent read and write 
operations. Note that an existing file must not be accessed until a 
sucessful open operation is completed. Upon return, the open function 
returns a "directory code" with the value 0 through 3 if the open was 
successful, or 0FFH (255 decimal) if the file cannot be found. If 
question marks occur in the FCB then the first matching FCB is 
activated. Note that the current record (“cr") must be zeroed by the 
program if the file is to be accessed sequentially from the first 
record. 
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*************************************** 
* * 

* FUNCTION 16s CLOSE FILE * 

* * 


*************************************** 


* Entry Parameters: 

* Register C: 10H 

* Registers DE : FCB Address 


* 

* 

* 

* 


* Returned Values * 

* Register As Directory Code * 

*************************************** 


The Close File function performs the inverse of the open file 
function. Given that the FCB addressed by DE has been previously 
activated through an open or make function (see functions 15 and 22) , 
the close function permanently records the new FCB in the referenced 
disk directory. The FCB matching process for the close is identical 
to the open function. The directory code returned for a successful 
close operation is 0, 1, 2, or 3, while a 0FFH (255 decimal) is 
returned if the file name cannot be found in the directory. A file 
need not be closed if only read operations have taken place. If write 
operations have occurred,, however, the close operation is necessary to 
permanently record the new directory information. 
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*************************************** 
* * 

* FUNCTION 17: SEARCH FOR FIRST * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 11H * 

* Registers DE: FCB Address * 

* * 

* Returned Value: * 


* Register A: Directory Code * 
*************************************** 

Search First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise 0, 1, 2, or 3 is returned 
indicating the file is present. In the case that the file is found, 
the current DMA address is filled with the record containing the 
directory entry, and the relative starting position is A * 32 (i.e. , 
rotate the A register left 5 bits, or ADD A five times). Although not 
normally required for application programs, the directory information 
can be extracted from the buffer at this position. 

An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from “fl" through “ex'* matches the corresponding field of any 
directory entry on the default or auto-selected disk drive. If the 
"dr" field contains an ASCII question mark, then the auto disk select 
function is disabled, the default disk is searched, with the search 
function returning any matched entry, allocated or free, belonging to 
any user number. This latter function is not normally used by 
application programs, but does allow complete flexibility to scan all 
current directory values. If the "dr" field is not a question mark, 
the “s2" byte is automatically zeroed. 


**************************************& 
* * 


* FUNCTION 18: SEARCH FOR NEXT * 

* is 

a************************************** 


★ 

Entry Parameters: 


it 

★ 

* 

Register C: 

12H 

is 

is 

it 

Returned Value: 


★ 

* 

Register A: 

Directory Code 

* 


*************************************** 


The Search Next function is similar to the Search First 
function, except that the directory scan continues from the last 
matched entry. Similar to function 17, function 18 returns the 
decimal value 255 in A when no more directory items match. 
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* FUNCTION 19: DELETE FILE * 

* * 
*************************************** 


* 

Entry Parameters: 

* 

* 

Register C : 

13H * 

* 

* 

Registers DE: 

FCB Address * 

* 

* 

Returned Values 

* 

* 

Register A? 

Directory Code * 


*************************************** 


The Delete File function removes files which match the FCB 
addressed by DE. The filename and type may contain ambiguous 
references (i.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search Next 
functions. 


Function 19 returns a decimal 255 if the referenced file or 
files cannot be found, otherwise a value in the range 0 to 3 is 
returned. 


*************************************** 
* * 

* FUNCTION 20: READ SEQUENTIAL * 

* * 

*************************************** 


* 

Entry Parameters: 


* 

* 

Register C: 

14H 

* 

* 

is 

Registers DE: 

FCB Address 

* 

* 

* 

Returned Value: 


* 

* 

Register As 

Directory Code 

* 


*************************************** 


Given that the FCB addressed by DE has been activated through an 
open or make function (numbers 15 and 22), the Read Sequential 
function reads the next 128 byte record from the file into memory at 
the current DMA address, the record is read from position ,, cr“ of the 
extent, and the "cr“ field is automatically incremented to the next 
record position. If the "cr" field overflows then the next logical 
extent is automatically opened and the “cr“ field is reset to zero in 
preparation for the next read operation. The value 00H is returned in 
the A register if the read operation was successful, while a non-zero 
value is returned if no data exists at the next record position (e.g. , 
end of file occurs) . 
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*************************************** 
* * 

* FUNCTION 21: WRITE SEQUENTIAL * 

* * 




* 

Entry Parameters: 


it 

★ 

Register C: 

15H 

it 

* 

* 

Registers DE: 

FCB Address 

it 

it 

* 

Returned Value: 


it 

* 

Register A: 

Directory Code 

* 


*************************************** 


Given that the FCb addressed by DE has been activated through an 
open or make function (numbers 15 and 22) , the Write Sequential 
function writes the 128 byte data record at the current DMA address to 
the file named by the FCB. the record is placed at position "cr“ of 
the file, and the "cr“ field is automatically incremented to the next 
record position. If the ”cr“ field overflows then the next logical 
extent is automatically opened and the “cr" field is reset to zero in 
preparation for the next write operation. Write operations can take 
place into an existing file, in which case newly written records 
overlay those which already exist in the file. Register A = 00H upon 
return from a successful write operation, while a non-zero value 
indicates an unsuccessful write due to a full disk. 


* * 

* FUNCTION 22: MAKE FILE * 

* * 


* 

Entry Parameters: 


★ 

* 

Register C: 

16H 

★ 

★ 

it 

Registers DE : 

FCB Address 

* 

it 

it 

Returned Value: 


* 

it 

Register A: 

Directory Code 

* 


*************************************** 


The Make File operation is similar to the open file operation 
except that the FCB must name a file which does hot exist in the 
currently referenced disk directory (i.e„, the one named explicitly by 
a non-zero “dr" code, or the default disk if “dr“ is zero) . The FDOS 
creates the file and initializes both the directory and main memory 
value to an empty file. The programmer must ensure that no duplicate 
file names occur, and a preceding delete operation is sufficient if 
there is any possibility of duplication. Upon return, register A * 0 , 
1, 2, or 3 if the operation was successful and 0FFH (255 decimal) if 
no more directory space is available. The make function has the 
side-effect of activating the FCB and thus a subsequent open is not 
necessary. 


(All Information Contained Herein is Proprietary to Digital Research.) 

19 



*************************************** • 
* * 


* FUNCTION 23; RENAME FILE * 

is * 


*************************************** 


* Entry Parameters: 

* Register C: 17H 

* Registers DE: FCB Address 


* 

* 

* 

* 


* Returned Value; * 

* Register A; Directory Code * 
********************* ******* *********** 


The Rename function uses the FCB addressed by DE to change all 
occurrences of the file named in the first 16 bytes to the file named 
in the second 16 bytes. The drive code "dr" at position 0 is used to 
select the drive, while the drive code for the new file name at 
position 16 of the FCB is assumed to be zero. Upon return, register A 
is set to a value between 0 and 3 if the rename was successful, and 
0FFH (255 decimal) if the first file name could not be found in the 
directory scan. 


*************************************** 

* * 

* FUNCTION 24: RETURN LOGIN VECTOR * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 18H * 

* * 

* Returned Value: * 

* Registers HL: Login Vector * 
*************************************** 

The login vector value returned by CP/M is a 16-bit value in HL, 
where the least significant bit of L corresponds to the first drive A, 
and the high order bit of H corresponds to the sixteenth drive, 
labelled P. A '*0 ,c bit indicates that the drive is not on-line, while 
a “I” bit marks an drive that is actively on-line due to an explicit 
disk drive selection, or an implicit drive select caused by a file 
operation which specified a non-zero "dr" field. Note that 
compatibility is maintained with earlier releases, since registers A 
and L contain the same values upon return. 
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*************************************** 

* * 

* FUNCTION 25: RETURN CURRENT DISK * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 19H * 

* * 

* Returned Value: * 

* Register A: Current Disk * 
*************************************** 

Function 25 returns the currently selected default disk number 
in register A. The disk numbers range from 0 through 15 corresponding 
to drives A through P. 


*************************************** 

* * 

* FUNCTION 26: SET DMA ADDRESS * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 1AH * 

* Registers DE: DMA Address * 

* * 

*************************************** 

**DMA“ is an acronym for Direct Memory Address, which is often 
used in connection with disk controllers which directly access the 
memory of the mainframe computer to transfer data to and from the disk 
subsystem. Although many computer systems use non-DMA access (i.e., 
the data is transfered through programmed I/O operations) , the DMA 
address has, in CP/M, come to mean the address at which the 128 byte 
data record resides before a disk write and after a disk read. Upon 
cold start, warm start, or disk system reset, the DMA address is 

automatically set to BOOT+0080H. The Set DMA function, however, can 
be used to change this default value to address another area of memory 
where the data records reside. Thus, the DMA address becomes the 
value specified by DE until it is changed by a subsequent Set DMA 
function, cold start, warm start, or disk system reset. 
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********************* ****************** 
* * 
* FUNCTION 27: GET ADDR (ALLOC) * 


* 

* 

* 

* 


Entry Parameters: * 

Register C: 1BH * 

* 


* Returned Value: * 

Registers HL: ALLOC Address * 
*************************************** 


on~l i n^ n vector" is maintained in main memory for each 

provided by the fllScaMnn^ 10 ^ P ro ^ raiT,s “se the information 

proviaea oy the allocation vector to determine the amount of remaining 

of thl < f 1 e f n th ®. STAT program) * Function 27 returns the base addresl 
°J, * h *. avocation vector for the currently selected disk drive The 

hii hlo° n inf °™ atlon ma Y • however, be invalid if the selected* disk 

used bv aoolicaMn rea<37on ly' Although this function is not normally 
, y application pr ograms , additional details the allorahinn 

vector are found in the "CP/M Alteration Guide. " allocation 


********************** ***************** 
* * 

* FUNCTION 28: WRITE PROTECT DISK * 

* * 
********************** ***************^ 

* Entry Parameters: * 

* Register C: 1CH * 

* 

* 

****************************** ****^ a ^ 


The disk write protect function 
protection for the currently selected disk 
the disk, before the next cold or warm 
me s s ag e 


provides temporary write 
. Any attempt to write to 
start operation produces the 


Bdos Err on d: R/O 
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*************************************** 
* * 

* FUNCTION 29: GET READ /ONLY VECTOR * 

* * 

*************************************** 


* Entry Parameters: 

* Register C: 1DH 

* 


★ 

★ 

* 


* Returned Value: * 

* Registers HL: R/O Vector Value* 
*************************************** 


Function 29 returns a bit vector in register pair HL which 
indicates drives which have the temporary read/only bit set. Similar 
to function 24, the least significant bit corresponds to drive A, 
while the most significant bit corresponds to drive P. The R/0 bit is 
set either by an explicit call to function 28, or by the automatic 
software mechanisms within CP/M which detect changed disks. 


*************************************** 
* * 

* FUNCTION 30: SET FILE ATTRIBUTES * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 1EH * 

* Registers DE: FCB Address * 

* * 

* Returned Value: * 

* Register A: Directory Code * 

*************************************** 


The Set File Attributes function allows programmatic 
manipulation of permanent indicators attached to files. In 

particular, the R/O and System attributes ( tl ' and t2 ‘ ) can be set or 
reset. The DE pair addresses an unambiguous file name with the 
appropriate attributes set or reset. Function 30 searches for a 
match, and changes the matched directory entry to contain the selected 
indicators. Indicators fl‘ through f4‘ are not presently used, but 
may be useful for applications programs, since they are not involved 
in the matching process during file open and close operations. 

Indicators f5‘ through f8‘ and t3 ' are reserved for future system 
expansion. 
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*************************************** 
* * 

* FUNCTION 31: GET ADDR (DISK PA RMS) * 

* * 
*************************************** 

* Entry Parameters: * 

* Register C: 1FH * 

* * 

* Returned Value: * 

* Registers HLs DPB Address * 

*************************************** 


The address of the BIOS resident disk parameter block is 
returned in HL as a result of this function call. This address can be 
used for either of two purposes. First, the disk parameter values can 
be extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk parameters 
when the disk environment changes, if required. Normally, application 
programs will not require this facility. 




* 

- 

* 

* 

* 

FUNCTION 32: SET/GET USER CODE * 

* 

* * 

************************************* 

* 

Entry Parameters: 

* 

* 

Register C: 

20H * 

* 

Register E: 

0FFH (get) or * 

* 

* 

User Code (set) * 

* 

* 

Returned Value: 

* 

* 

Register A: 

Current Code or * 

* 

(no value) * 

*************************************** 


An application program can change or interrogate the currently 
active user number by calling function 32. If register E - 0FFH, then 
the value of the current user number is returned in register A, where 
the value is in the range 0 to 31. If register E is 


the current user number is changed to the value of E 


not 0FFH , 
(modulo 32) 


then 
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* * 


* FUNCTION 33: READ RANDOM * 

* * 

*************************************** 


* 

Entry Parameters: 


* 

* 

Register C: 

21H 

* 

* 

Registers DE : 

FCB Address 

* 

* 



* 

* 

Returned Value: 


* 

* 

Register A: 

Return Code 

* 


*************************************** 

The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation takes 
place at a particular record number, selected by the 24-bit value 
constructed from the three byte field following the FCB (byte 
positions r0 at 33, rl at 34, and r2 at 35) . Note that the sequence 
of 24 bits is stored with least significant byte first (r0) , middle 
byte next (rl) , and high byte last (r2) . CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 
must be zero, however, since a non-zero value indicates overflow past 
the end of file. 

Thus, the r0,rl byte pair is treated as a double-byte, or "word" 
value, which contains the record to read. This value ranges from 0 to 
65535, providing access to any particular record of the 8 megabyte 
file. In order to process a file using random access, the base extent 
(extent 0) must first be opened. Although the base extent may or may 
not contain any allocated data, this ensures that the file is properly 
recorded in the directory, and is visible in DIR requests. The 
selected record number is then stored into the random record field 
(r0,rl), and the BDOS is called to read the record. Upon return from 
the call, register A either contains an error code, as listed below, 
or the value 00 indicating the operation was successful. In the 
latter case, the current DMA address contains the randomly accessed 
record. Note that contrary to the sequential read operation, the 
record number is not advanced. Thus, subsequent random read 
operations continue to read the same record. 

Upon each random read operation, the logical extent and current 
record values are automatically set. Thus, the file can be 
sequentially read or written, starting from the current randomly 
accessed position. Note, however, that in this case, the last 
randomly read record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation. You can, of course', simply advance 
the random record position following each random read or write to 
obtain the effect of a sequential I/O operation. 

Error codes returned in register A following a random read are 
listed below. 
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01 reading unwritten data 

02 (not returned in random mode) 

03 cannot close current extent 

04 seek to unwritten extent 

05 (not returned in read mode) 

06 seek past physical end of disk 

Error code 01 and 04 occur when a random read operation accesses a 
data block which has not been previously written, or an extent which 
has not been created, which are equivalent conditions*, Error 3 does 
not normally occur under proper system operation, but can be cleared 
by simply EQ—rsading # or re-opening extent zero as long as the disk is 
not physically write protected. Error code 06 occurs whenever byte r2 
is non-zero under the current 2.0 release. Normally, non— zero return 
codes can be treated as missing data, with zero return codes 
indicating operation complete. 
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★ * 


* FUNCTION 34: WRITE RANDOM * 

* * 

★★a************************************ 


* 

Entry Parameters: 


* 

* 

Register C: 

22H 

* 

* 

Registers DE: 

FCB Address 

* 

* 



* 

* 

Returned Value: 


★ 

* 

Register A: 

Return Code 

* 


*************************************** 


The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is the 
target of the write has not yet been allocated, the allocation is 
performed before the write operation continues. As in the Read Random 
operation, the random record number is not changed as a result of the 
write. The logical extent number and current record positions of the 
file control block are set to correspond to the random record which is 
being written. Again, sequential read or write operations can 
commence following a random write, with the notation that the 
currently addressed record is either read or rewritten again as the 
sequential operation begins. You can also simply advance the random 
record position following each write to get the effect of a sequential 
write operation. Note that in particular, reading or writing the last 
record of an extent in random mode does not cause an automatic extent 
switch as it does in sequential mode. 

The error codes returned by a random write are identical to the 
random read operation with the addition of error code 05, which 
indicates that a new extent cannot be created due to directory 
o ve r f 1 ow . 
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*&★*******?***************■*********&*#&* 

* * 

* FUNCTION 35: COMPUTE FILE SIZE * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 23H * 

* Registers DEs FCB Address * 

* * 

* Returned Values * 

* Random Record Field Set * 

*************************************** 

When computing the size of a file, the DE register pair 
addresses an FCB in random mode format (bytes r0, rl, and r2 are 
present). The FCB contains an unambiguous file name which is used in 
the directory scan. Upon return, the random record bytes contain the 
“virtual" file size which is, in effect, the record address of the 
record foilwing the end of the file. if, following a call to 
function 35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536. Otherwise, bytes r0 and rl constitute a 
16“bit value (r0 is the least significant byte, as before) which is 
the file size. 

Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end of 
file, then performing a sequence of random writes starting at the 
preset record address. 

The virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created 
in random mode and "holes" exist in the allocation, then the file may 
in fact contain fewer records than the size indicates. If, for 
example, only the last record of an eight megabyte file is written in 
random mode (i.e., record number 65535), then the virtual size is 
65536 records, although only one block of data is actually allocated. 
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*************************************** 
* * 

* FUNCTION 36: SET RANDOM RECORD * 

* * 

*************************************** 

* Entry Parameters: * 

* Register C: 24H * 

* Registers DE: FCB Address * 

* * 

* Returned Value: * 

* Random Record Field Set * 

*************************************** 


The Set Randan Record function causes the BDOS to automatically 
produce the random record position from a file which has been read or 
written sequentially to a particular point. The function can be 
useful in two ways. 

First, it is often necessary to initially read and scan a 
sequential file to extract the positions of various "key" fields. As 
each key is encountered, function 36 is called to compute the random 
record position for the data corresponding to this key. If the data 
unit size is 128 bytes, the resulting record position is placed into a 
table with the key for later retrieval. After scanning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
using the corresponding random record number which was saved earlier. 
The scheme is easily generalized when variable record lengths are 
involved since the program need only store the buffer-relative byte 
position along with the key and record number in order to find the 
exact starting position of the keyed data at a later time. 

A second use of function 36 occurs when switching from a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 
is called which sets th6 record number, and subsequent random read and 
write operations continue from the selected point in the file. 
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3. A SAMPLE FILE-TO-FILE COPY PROGRAM. 

The program shown below provides a relatively simple example of 
file operations. The program source file is created as COPY. ASM using 
the CP/M ED program and then assembled using ASM or MAC, resulting in 
a HEX " file. The LOAD program is the used to produce a COPY.COM file 
which executes directly under the CCP. The program begins by setting 
the stack pointer to a local area, and then proceeds to move the 
second name from the default area at 006CH to a 33-byte file control 
block called DFCB. The DFCB is then prepared for file operations by 
clearing the current record field. At this point, the source and 
destination FCB 8 s are ready for processing since the SFCB at 005CH is 
properly set-up by the CCP upon entry to the COPY program. That^ is, 
the first name is placed into the default fcb, with the proper fields 
sseroed, including the current record field at 007CH. The program 
continues by opening the source file, deleting any exising destination 
file, and then creating the destination file. If all this is 
successful, the program loops at the label COPY until each record has 
been read from the source file and placed into the destination file. 
Upon completion of the data transfer, the destination file is closed 
and the prog ran returns to the CCP command level by jumping to BOOT. 


sample f ile-to-f ile copy program 


6 



e 

9 

at the 

ccp level. 

the command 


9 

o 

9 


copy a:x. 

j b:u.v 


9 

o 

9 

copies 

the file named x.y from drive 


• 

9 

a to a 

file named 

u.v on drive b. 

0 000 = 

9 

boot 

equ 

0 0 0 0h 

system reboot 

0005 = 

fades 

equ 

00@5h 

bdos entry point 

005c ~ 

fcbl 

equ 

005ch ; 

first file name 

0 05c 3 

sfcb 

equ 

fcbl i 

source fcb 

006c s 

f cb2 

equ 

006ch j 

second file name 

0080 = 

dbuff 

equ 

0080h 

default buffer 

0100 = 

tpa 

equ 

0100h 

beginning of tpa 

0009 = 

9 

pr intf 

equ 

9 

print buffer func# 

0 00f 3 

openf 

equ 

15 

open file func# 

0010 - 

closef 

equ 

16 

close file func# 

0013 » 

deletef 

equ 

19 

delete file func# 

0014 - 

readf 

equ 

20 

sequential read 

0015 * 

wr i tef 

equ 

21 

sequential write 

0016 = 

makef 

equ 

22 ; 

make file func# 

0100 

9 

oeg 

tpa ; 

beginning of tpa 

0100 311b02 

• 

lxi 

sp, stack ; 

local stack 


9 

• 

9 

move second file 

name to dfcb 

0103 0el0 


ravi 

c 9 1 6 / 

half an fcb 
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0105 

116c00 


lxi 

d , f cb2 

source of move 

0108 

21da01 


lxi 

h , df cb 

destination fcb 

010b 

la 

mf cb: 

ldax 

d 

source fcb 

010c 

13 


inx 

d 

ready next 

0 10d 

77 


mov 

m,a 

dest fcb 

0 10e 

23 


inx 

h 

ready next 

0 10f 

0d 


dcr 

c 

count 16. . .0 

0110 

c20b01 

• 

jnz 

mf cb 

loop 16 times 



9 

• 

t 

name has been moved, zero cr 

0113 

af 


xra 

a 

a = 00h 

0114 

32fa01 


sta 

df cbcr 

current rec = 0 



9 

• 

9 

• 

source 

and destination fcb's ready 

0117 

115C00 

9 

lxi 

d , sfcb 

source file 

011a 

cd6 901 


call 

open 

error if 255 

0 lid 

118701 


lxi 

a, nofile 

ready message 

0120 

3c 


inr 

a 

255 becomes 0 

0121 

cc6101 

9 

cz 

finis 

done if no file 



9 

• 

9 

source 

file open, 

prep destination 

0124 

llda01 


lxi 

d,dfcb i 

destination 

0127 

cd7301 


call 

delete ; 

remove if present 

012a 

llda01 

9 

lxi 

d ,dfcb 

destination 

0 12d 

cd8201 


call 

make 

create the file 

0130 

119601 


lxi 

d,nodir ; 

ready message 

0133 

3c 


inr 

a ; 

255 becomes 0 

0134 

CC6101 

• 

cz 

finis ; 

done if no dir space 



9 

« 

9 

source 

file open, 

dest file open 



• 

9 

copy until end of file on source 

0137 

115C00 

9 

copy; 

lxi 

d ,sfcb 

source 

013a 

cd7801 


call 

read 

read next record 

013d 

b7 


ora 

a 

end of file? 

0 13e 

C25101 


jnz 

eof ile 

skip write if so 



9 

9 

9 

not end 

of file. 

write the record 

0141 

llda01 


lxi 

d ,df cb 

destination 

0144 

cd7d01 


call 

write 

write record 

0147 

lla901 


lxi 

d , space 

ready message 

014a 

b7 


ora 

a 

00 if write ok 

014b 

C46101 


cnz 

finis 

end if so 

0 14e 

C33701 

9 

jmp 

copy 

loop until eof 



9 

eof ile; 

; end of file, close destination 

0151 

llda01 


lxi 

d,dfcb 

destination 

0154 

cd6e01 


call 

close 

255 if error 

0157 

21bb01 


lxi 

h,wrprot 

ready message 

015a 

3c 


inr 

a 

255 becomes 00 

015b 

CC6101 

• 

cz 

finis 

shouldn't happen 



9 

m 

f 

copy operation complete, end 
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0 15e 

11CC01 


Ixi 

d, normal; ready message 



finis; 

l write 

message given by de, reboot 

0161 

0e09 


mvi 

c,pr intf 

0163 

cd0500 


call 

bdos ; write message 

0166 

c3 0000 


jmp 

boot ; reboot system 



9 

© 

9 

system 

interface subroutines 



o 

9 

(all return directly from bdos) 

0169 

0e0f 

9 

opens 

mvi 

c„openf 

016b 

C30500 


jmp 

bdos 

0 16e 

0el0 

9 

close; 

mvi 

c,closef 

0170 

C30500 


jmp 

bdos 

0173 

0el3 

9 

delete; 

mvi 

c,deletef 

0175 

C30500 


jmp 

bdos 

0178 

0el4 

9 

read ; 

mvi 

c^readf 

017a 

C30500 


jmp 

bdos 

0 17d 

0el5 

9 

wr ites 

mvi 

c„writef 

0 17f 

C30500 


jmp 

bdos 

0182 

0@16 

9 

make ; 

mvi 

c„make£ 

0184 

c3 0 500 


jmp 

bdos 



9 

9 

9 

console messages 

0187 

6e6f 20f nof ile; 

db 

‘no source file? 

0196 

6e6f 209nodir ; 

db 

‘no directory space? ' 

01a9 

6f7574f space; 

db 

‘out of data space? 8 

01bb 

7772695wrprot; 

db 

‘write protected?? 6 

0 ICC 

636f 700normal ; 

o 

db 

‘copy complete? 8 



9 

9 

data areas 

01da 


dfcb; 

ds 

33 ,• destination fcb 

01f a 


dfcbcr 

equ 

dfcb+32 ; current record 

0 Ifb 


9 

ds 

32 ; 16 level stack 



stack ; 



0 21b 



end 



Note that there are several simplifications in this particular 
program. First, there are no checks for invalid file names which 
could, for example, contain ambiguous references. This situation 
could be detected by scanning the 32 byte default area starting at 
location 005CH for ASCII question marks. A check should also be made 
to ensure that the file names have, in fact, been included (check 
locations 005DH and 006DH for non-blank ASCII characters). Finally, a 
check should be made to ensure that the source and destination file 
names are different. A speed improvement could be made by buffering 
more data on each read operation. One could, for example, determine 
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the size of memory by fetching FBASE from location 0006H and use the 
entire remaining portion of memory for a data buffer. In this case, 
the programmer simply resets the DMA address to the next successive 
128 byte area before each read. Upon writing to the destination file, 
the DMA address is reset to the beginning of the buffer and 
incremented by 128 bytes to the end as each record is transferred to 
the destination file. 
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4 „ A SAMPLE FILE DUMP UTILITY „ 


The file dump program shown below is slightly more complex than 
the simple copy program given in the previous section. The dump 
program reads an input file, specified in the CCP command line, and 
displays the content of each record in hexadecimal format at the 
console. Note that the dump program saves the CCP’s stack upon entry, 
resets the stack to a local area, and restores the CCP's stack before 
returning directly to the CCP. Thus, the dump program does not 
perform and warm start at the end of processing. 

f DUMP program reads input file and displays hex data 


0100 


org 

10 0h 


0 0 05 

= bdos 

equ 

0005h 

,*do.s entry point 

0001 

- cons 

equ 

1 

jread console 

0002 

-= typef 

equ 

2 

type function 

0009 

- pr intf 

equ 

9 

; buffer print entry 

0 00b 

■- brkf 

equ 

11 

jbreak key function (true if char 

0 00f 

= openf 

equ 

15 

;£ile open 

0014 

-■ r e ad f 

equ 

20 

;read function 

0 05c 

o 

- f cb 

equ 

5ch 

ifile control block address 

0080 

* buff 

equ 

80h 

j input disk buffer address 


P 

« 

6 

non graphic characters 

0 00d 

- cr 

equ 

0dh 

^carnage return 

0 00a 

= If 

equ 

0ah 

?line feed 


e 

• 

9 

file 

control block definitions 

005c 

- fcbdn 

equ 

fcb+0 

;disk name 

005d 

- fcbfn 

equ 

fcb+1 

;file name 

0065 

= fcbft 

equ 

fcb+9 

;disk file type (3 characters) 

0068 

- fcbrl 

equ 

fcb+1 2 

; file’s current reel number 

0 06b 

= fcbrc 

equ 

fcb+1 5 

;file's record count (0 to 128) 

007c 

- fcbcr 

equ 

fcb+3 2 

; current (next) record number (0 

007d 

- fcbln 

• 

equ 

fcb+33 

;fcb length 


• 

t 

set up stack 


0100 

210000 

Ixi 

h, 0 


0103 

39 

dad 

sp 



• 

9 

entry stack pointer in hi from the ccp 

0104 

221502 

shld 

oldsp 

stack area (restored at finis) 


• 

f 

set sp to local 

0107 

315702 

lxi 

sp,s tktop 


0 

t 

read 

and print 

successive buffers 

010a 

cdcl01 

call 

setup 

; set up input f ile 

010d 

feff 

cpi 

255 

; 255 if file not present 

010f 

c21b01 

jnz 

openok 

; skip if open is ok 


9 

• 

9 

file 

not there. 

give error message and return 

0112 

Ilf 301 

lxi 

d ,opnmsg 

0115 

cd9c01 

call 

err 


0118 

C35101 

jmp 

finis 

; to return 
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open ok: 

; open 

operation ok, set buffer index to end 

011b 

3e80 


mvi 

a, 8 0h 

01 Id 

321302 


sta 

ibp ;set buffer pointer to 80h 



• 

9 

hi contains next address to print 

0120 

210000 


lxi 

h,0 ystart with 0000 



/ 

gloop: 



0123 

e5 


push 

h ;save line position 

0124 

cda201 


call 

gnb 

0127 

el 


pop 

h ;recall line position 

0128 

da5101 


jc 

finis ;carry set by gnb if end fil 

012b 

47 


mov 

b,a 



• 

/ 

print 

hex values 



• 

9 

check 

for line fold 

012c 

7d 


mov 

a,l 

0 12d 

e60f 


ani 

0fh ;check low 4 bits 

0 12f 

c2 4401 


jnz 

nonum 



• 

9 

print 

line number 

0132 

cd7201 


call 

crlf 



9 

• 

9 

check 

for break key 

0135 

cd5901 


call 

break 



• 

9 

accum 

lsb = 1 if character ready 

0138 

0f 


rrc 

;into carry 

0139 

da5101 


jc 

finis ;don’t print any more 

013c 

7c 

9 

mov 

a,h 

013d 

cd8f 01 


call 

phex 

0140 

7d 


mov 

a, 1 

0141 

cd8f 01 


call 

phex 



nonum: 



0144 

23 


inx 

h ?to next line number 

0145 

3e20 


mvi 

a, ' • 

0147 

cd6501 


call 

pchar 

014a 

78 


mov 

a, b 

014b 

cd3f 01 


call 

phex 

0 14e 

C32301 


jmp 

gloop 



9 

finis: 





• 

9 

end o i 

: dump, return to ccp 



• 

9 

(note 

that a jmp to 0000h reboots) 

0151 

cd7201 


call 

crlf 

0154 

2al502 


Ihld 

oldsp 

0157 

f 9 


sphl 




« 

9 

stack 

pointer contains ccp ’ s stack location 

0158 

c9 

• 

9 

ret 

;to the ccp 



• 

9 

e 

9 

subroutines 



9 

break: 

? check 

; break key (actually any key will do) 

0159 

e5d5c5 


push h 

il push d! push b; environment saved 

015c 

0e0b 


mvi 

c,brkf 

0 15e 

cd0 500 


call 

bdos 

0161 

cldlel 


pop bl 

pop a! pop h; environment restored 
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0164 

c9 


ret 





0 

pchar: 

; print 

a character 

i 

0165 

e5d5c5 


push hi 

push dl push bs saved 

£ v. 

0168 

0e0 2 


mvi 

c,typef 

,J A 

016a 

5f 


mov 

e,a 

1 

016b 

cd0500 


call 

bdos 

| 

016e 

cldlel 


pop b! 

pop d! pop hs restored 


0171 

c9 


ret 


fl 



crlf : 




0172 

3e0d 


mvi 

a,cr 


0174 

cd6501 


call 

pchar 

| 

0177 

3e0a 


mvi 

a. If 


0179 

cd6501 


call 

pchar 


017c 

c9 

C 

9 

ret 


1 



e 

9 

pn.ib : 

sprint 

nibble in reg a 

1 

0 17d 

e60f 


ani 

0£h slow 4 bits 

1 

0 17f 

f e0a 


cpi 

10 

fl 

0181 

d28901 


jnc 

pl0 




9 

9 

less than or equal to 9 

\ 

0184 

c630 


adi 

’0' 


0186 

c38b01 


jmp 

prn 




0 

® 

t 

greater or equal to 10 


0189 

c637 

pl0: 

adi 

•a' - 10 


018b 

cd6 501 

prn; 

call 

pchar 


018e 

c9 


ret 


L... ) 



9 

phex : 

sprint 

hex char in reg a 


018f 

f 5 


push 

psw 


0190 

0f 


r rc 



0191 

0 f 


rrc 



0192 

0 f 


rrc 



0193 

0£ 


rrc 



0194 

cd7d01 


call 

pnib spcint nibble 


0197 

fl 


pop 

psw 


0198 

cd7d01 


call 

pnib 


019b 

c9 

• 

ret 





9 

errs 

sprint 

error message 




« 

9 

d„e addresses message ending with 


019c 

0e09 


mvi 

c,print£ sprint buffer function 


0 19e 

cd0 500 


call 

bdos 


01al 

c9 

c 

9 

ret 





o 

9 

gnbs 

sget next byte 


0 la 2 

3al302 


Ida 

ibp 


01a5 

f e80 


cpi 

80h 


01a7 

c2b301 


jnz 

g0 




e 

9 

• 

9 

read another buffer 
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/ 


01aa 

cace01 


call 

diskr 

0 lad 

b7 


ora 

a ;zero value if read ok 

01ae 

cab301 


jz 

g0 ;for another byte 



• 

/ 

end of data, return with carry set for eof 

01bl 

37 


stc 


01b2 

c9 


ret 




g0 : 

;read the byte at buff+reg a 

01b3 

5f 


mov 

e,a ;ls byte of buffer index 

01b4 

1600 


mvi 

d,0 ;double precision index to de 

01b6 

3c 


inr 

a ; index=index+l 

01b7 

321302 


sta 

ibp ;back to memory 



• 

9 

pointer 

is incremented 



• 

9 

save the current file address 

0 lba 

218000 


lxi 

h,buf f 

01bd 

19 


dad 

d 



• 

9 

absolute character address is in hi 

01be 

7e 


mov 

a,m 



• 

9 

byte is 

in the accumulator 

01bf 

b7 


ora 

a preset carry bit 

01c0 

c9 


ret 




9 

setup: 

;set up 

file 



■ • 

9 

open the file for input 

01cl 

af 


xra 

a ;zero to accum 

0 lc2 

327C00 


sta 

feber ;clear current record 

01c5 

115C00 

9 

lxi 

d, feb 

0 lc8 

0e0f 


mvi 

c,openf 

0 lea 

cd0500 


call 

bdos 



• 

9 

255 in 

accum if open error 

01cd 

c9 


ret 




9 

diskr : 

?read disk file record 

01ce 

e5d5c5 


push hi 

push d! push b 

0 ldl 

115c00 


lxi 

d , feb 

01d4 

0el4 


mvi 

c,, r.eadf 

01d6 

cd0500 


call 

bdos 

01d9 

cldlel 


pop bi 

pop d! pop h 

01dc 

c9 


ret 




/ 

o 

9 

fixed message area 

0 Idd 

46494c0signon: 

db 

"file dump version 2.0$ 

01f 3 

0d0a4e0opnmsg % 

dfe 

cr,lf , 'no input file present on disk$ 



o 

9 

variable area 

0213 


ibp: 

ds 

2 ; input buffer pointer 

0215 


oldsp: 

ds 

2 ; entry sp value from ccp 



9 

» 

9 

stack area 

0217 



ds 

64 preserve 32 level stack 


sfcktop: 


0257 


end 
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5, A SAMPLE RANDOM ACCESS PROGRAM . 

This manual is concluded with a rather extensive, but complete 
example of randan access operation. The program listed below performs 
the simple function of reading or writing random records upon command 
from the terminal. Given that the program has been created, 
assanbled , and placed into a file labelled RANDOM.COM, the COP level 
command s 


RANDOM X .DAT 

starts the test program. The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 

next command? 

and is followed by operator input, terminated by a carriage return. 
The input commands take the form 

nW nR Q 

where n is an integer value in the range 0 to 65535, and W, R, and Q 
are simple command . characters corresponding to random write, random 
read, and quit processing, respectively. If the W command is issued, 
the RANDCM program issues the prompt 

type data; 

The operator then responds by typing up to 127 characters, followed by 
a carriage return. RANDCM then writes the character string into the 
X.DAT file at record n. If the R command is issued, RANDCM reads 
record number n and displays the string value at the console. If the 
Q command is issued, the X.DAT file is closed, and the program returns 
to the console command processor. In the interest of brevity, the 
only error message is 

error, try again 

The program begins with an initialization section where the 
input file is opened or created, followed by a continuous loop at the 
label "ready'' where the individual commands are interpreted. The 
default file control block at 005CH and the default buffer at 0080H 
are used in all disk operations. The utility subroutines then follow, 
which contain the principal input line processor, called "readc." 
This particular program shows the elements of random access 

processing, and can be used as the basis for further program 

development. 
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0100 


• * * 

;* sample randan access program for cp/m 2.0 * 

• * * 

org 100h ;base of tpa 

O 

0 000 


t 

reboot 

equ 

0 0 00h 

;system reboot 

0005 

= 

bdos 

• 

equ 

0 005h 

;bdos entry point 

0001 

= 

i 

coninp 

equ 

1 

;console input function 

0002 

3 

conout 

equ 

2 

; console output function 

0009 

= 

pstring 

equ 

9 

;print string until ’$* 

000a 

= 

rstring 

equ 

10 

;read console buffer 

0 00c 

= 

version 

equ 

12 

; return version number 

000f 

= 

openf 

equ 

15 

;file open function 

0010 

= 

closef 

equ 

16 

; close function 

0016 

= 

makef 

equ 

22 

;make file function 

0021 

= 

readr 

equ 

33 

;read random 

0022 

3 

writer 

equ 

34 

;write random 

005c 

3 

fcb 

equ 

0 05ch 

;default file control block 

0 07d 

= 

ranrec 

equ 

fcb+33 

;random record position 

0 07f 

= 

ranovf 

equ 

fcb+35 

;high order (overflow) byte 

0080 

3 

buff 

equ 

0 080h 

;buffer address 

0 00d 

3 

9 

cr 

equ 

0dh 

;carriage return 

0 00a 

= 

if 

Q 

t 

equ 

0ah 

;line feed 


* * 

* load SP, set-up file for random access * 

* * 


0100 

31bc0 

• 

Ixi 

sp, stack 



9 

o 

9 

version 

2.0? 

0103 

0e0c 


mvi 

c, version 

0105 

cd050 


call 

bdos 

0108 

fe20 


cpi 

20h ;version 2.0 or better? 

010a 

d2160 


jnc 

versok 



• 

9 

bad version, message and go back 

010d 

11150 


Ixi 

d ,badver 

0110 

cdda0 


call 

print 

0113 

c3000 

• 

jmp 

reboot 



9 

versok: 





• 

i 

correct 

version for random access 

0116 

0e0f 


mvi 

c, openf ;open default fcb 

0118 

115c0 


Ixi 

d ,fcb 

011b 

cd0 50 


call 

bdos 

011e 

3c 


inr 

a ;err 255 becomes zero 

011f 

C2370 


jnz 

ready 


cannot open file, so create it 
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0122 0eX6 
0124 115c0 
0127 cd0 50 
012a 3c 
012b C2370 


0 X2e 113a0 
0131 cdda0 
0134 C3000 


mvi c,make£ 

lxi d,fcb 

call bdos 

inr a ;err 255 becomes zero 

jnz ready 


; cannot create file, directory full 

lxi d, nospace 

call print 

jmp reboot ,*back to ccp 

O 

!*************************************************** 
9 ^ * 

* 
* 


• * loop back to "ready" after each command 


i * 


. **************************************************** 
9 

o 

9 

ready: 

; file is ready for processing 


0137 

cde5 0 

9 

call 

readcom 

iread next command 

013a 

227d0 


shld 

ranree 

fstore input record# 

013d 

217f 0 


lxi 

h, ranovf 


0140 

3600 


mvi 

m , 0 

iclear high byte if set 

0142 

f e5 1 


cpi 

'Q' 

iguit? 

0144 

C2560 


jnz 

notq 




9 

• 

9 

quit processing. 

close file 

0147 

0el0 


mvi 

c,clos@f 


0149 

115c0 


lxi 

d , fcb 


014c 

cd0 50 


call 

bdos 


0 14f 

3c 


inr 

a 

jerr 255 becomes 0 

0150 

cab90 


jz 

error 

;errot message, retry 

0153 

c3 000 


jmp 

reboot 

;back to ccp 



9 

o ★ is is is * 

9 

******************************************* 5 



© is 

9 

i * end 

of quit command. 

process write 



[************************************************ 

a 



notq: 






o 

/ 

not the 

quit command, random write? 

0156 

f e57 


cpi 

•w 


0158 

C2890 


jnz 

notw 




9 

• 

9 

this is 

a random 

i write, fill buffer until 

015b 

114d0 


lxi 

d ,datmsg 

0 15e 

cdda0 


call 

print 

;data prompt 

0161 

0e7f 


mvi 

c,127 

; up to 127 characters 

0163 

21800 


lxi 

h,buf f 

;destination 



rloops 

;read next character to buff 

0166 

c5 


push 

b 

;save counter 

0167 

e5 


push 

h 

;next destination 

0168 

cdc20 


call 

getchr 

;character to a 

016b 

el 


pop 

h 

; restore counter 


* 

is 

is 
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016c 

cl 



pop 

b 

; restore next to fill 

0 16d 

f e0d 



cpi 

cr 

;end of line? 

0 16f 

ca780 



jz 

erloop 






not end, store character 

0172 

77 



mov 

m,a 


0173 

23 



inx 

h 

;next to fill 

0174 

0d 



dcr 

c 

; counter goes down 

0175 

C2660 



jnz 

rloop 

?end of buffer? 



erloop; 






1 


end of read loop 

, store 00 

0178 

3600 

# 

mvi 

m,0 






write 

the record 

to selected record number 

017a 

0e22 



mvi 

c, writer 


017c 

115C0 



lxi 

d ,fcb 


0 17f 

cd0 50 



call 

bdos 


0182 

b7 



ora 

a 

;error code zero? 

0183 

c2b90 



jnz 

error 

; message if not 

0186 

C3370 



jmp 

ready 

;for another record 




I************************************************* 




* end 

* 

of write command. 

process read 




.************************************************* 



notw: 






* 


not a 

write command, read record? 

0189 

f e52 



cpi 

'R* 


018b 

c2b90 

• 

jnz 

error 

;skip if not 





read 

random record 

018e 

0e21 



mvi 

c, readr 


0190 

115c0 



lxi 

d,fcb 


0193 

cd050 



call 

bdos 


0196 

b7 



ora 

a 

; return code 00? 

0197 

c2b90 



jnz 

error 




i 


read 

was successful, write to console 

019a 

cdcf 0 



call 

crlf 

; new line 

019d 

0e80 



mvi 

c, 128 

;max 128 characters 

0 19f 

21800 



lxi 

h,buf f 

;next to get 



wloop: 




01a2 

7e 



mov 

a,m 

;next character 

01a3 

23 



inx 

h 

;next to get 

01a 4 

e67f 



ani 

7fh 

;mask parity 

01a6 

ca370 



jz 

ready 

;for another command if 00 

01a9 

c5 



push 

b 

?save counter 

01aa 

e5 



push 

h 

; save next to get 

01ab 

f e20 



cpi 

1 8 

; graphic? 

01ad 

d4c80 



cnc 

putchr 

;skip output if not 

01b0 

el 



pop 

h 


0 lbl 

cl 



pop 

b 


01b2 

0d 



dcr 

c 

;count=count“l 

01b3 

c2a20 



jnz 

wloop 


01b6 

C3370 



jmp 

ready 
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* * 

* 
* 


?* end of read command, all errors end-up here 

e * 

9 




errors 


0 Xb9 

11590 

Ixi 

d„errmsg 

0 Ibc 

cdda0 

call 

print 

0 Ibf 

C3370 

jmp 

C 

ready 



9 



9 

; * utility subroutines for console i/o 
• * 



9 

. ****************************★**********★********' 

9 



getchr : 




?read 

next console character to a 

0 lc2 

0e0 1 

mvi 

c,coninp 

0 lc4 

cd050 

call 

bdos 

0 lc7 

c9 

ret 




9 

putchr: 




jwrite character from a to console 

0 lc8 

0e0 2 

mvi 

c,conout 

01ca 

5f 

mov 

e»a ^character to send 

0 leb 

cd0 50 

call 

bdos ; send character 

0 Ice 

c9 

ret 




cr If ? 




; send 

carriage return line feed 

01cf 

3@0d 

mvi 

a,cr ;carriage return 

0 ldl 

cdc80 

call 

putchr 

01d4 

3e0a 

mvi 

a, If ?line feed 

01d6 

cdc80 

call 

putchr 

01d9 

c9 

ret 

e 




/ 

print: 




;print the buffer addressed by de until $ 

01da 

d5 

push 

d 

01db 

cdcf 0 

call 

crlf 

0 Ide 

dl 

pop 

d ;new line 

01df 

0e0 9 

mvi 

c,pstring 

01el 

cd050 

call 

bdos ;print the string 

01e4 

c9 

ret 

Q 




9 

readcom: 




; read 

the next command line to the conbuf 

01e5 

116b0 

lxi 

d, prompt 

01e8 

cdda0 

call 

print ; command? 

01eb 

0e0a 

mvi 

c,r string 

0 led 

117a0 

lxi 

d , conbuf 

0 If 0 

cd0 50 

call 

bdos ;read command line 



; command line is present, scan it 


* 

* 

* 
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0 If 3 

21000 


lxi 

h,0 ;start with 0000 

0 If 6 

117C0 


lxi 

d , conlin; command line 

0 If 9 

la readc: 

ldax 

d ;next command character 

01fa 

13 


inx 

d ; to next command position 

0 lfb 

b7 


ora 

a ; cannot be end of command 

0 If c 

c8 

• 

f 


rz 

not 

zero, numeric? 

0 lfd 

<3630 


sui 

'0* 

01ff 

f e0a 


cpi 

10 ;carry if numeric 

0201 <32130 


jnc 

endrd 

0204 

29 ’ 


add- 

dad 

in next digit 
h ; *2 

0205 

4d 


mov 

C,1 

0206 

44 


mov 

b,h ;bc = value * 2 

0207 

29 


dad 

h ; *4 

0208 

29 


dad 

h ; *8 

0209 

09 


dad 

b ;*2 + *8 » *10 

0 20a 

85 


add 

1 ;+digit 

020b 

6f 


mov 

1 ,a 

0 20c 

d2f 90 


jnc 

readc ;for another char 

0 20f 

24 


inr 

h ; overflow 

0210 

c3f 90 


jmp 

readc ;for another char 


endrd: 

• 

f 

end 

of read, restore value in a 

0213 

C630 


adi 

'0' ; command 

0215 

f e61 


cpi 

’a’ ; translate case? 

0217 

0218 

d8 

0 

e65f 


rc 

lower case, mask lower case bits 
ani 101$llllb 

0 21a 

021b 

c9 

t 

5 3 6f 7 9 

ret 

************** *********************** *********** 

* 

* string data area for console messages 

* 

************************************************ 

Dadver : 

db 'sorry, you need cp/m version 2$' 

0 23a 

nospace 

4e6f 29 

db 

'no directory space$* 

0 24d 

datmsg : 

547970 

db 

'type data: §' 

0259 

er rmsg % 

457272 

db 

'error, try again. $ ’ 

026b 

prompts 

4e6570 

db 

'next command? $ ' 


* 

★ 

* 
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9 


. if * 

9 * 

s* fixed and variable data area 

.* * 

.*************************************************** 

t 


027a 21 

conbuf : 

db 

conlen 

; length of console buffer 

0 27b 

consiz: 

ds 

1 

; resulting size after read 

0 27c 

conlins 

ds 

32 

^length 32 buffer 

0021 38 

conlen 

equ 

$-consiz 


0 29c 

0 2bc 

e 

9 

stacks 

ds 

end 

32 

s 16 level stack 


Again, major improvements could be made to this particular 
program to enhance its operation. In fact, with some work, this 
program could evolve into a simple data base management system. One 
could, for example, assume a standard record size of 128 bytes, 
consisting of arbitrary fields within the record. A program, called 
GETKEY, could be developed which first reads a sequential file and 
extracts a specific field defined by the operator. For example, the 
command 

GETKEY NAMES. OAT LASTNAME 10 20 

would cause GETKEY to read the data base file NAMES.DAT and extract 
the 16 LAS THAME " field from each record, starting at position 10 and 
ending at character 20. GETKEY builds a table in memory consisting of 
each particular LASTNAME field, along with its 16-bit record number 
location within the file. The GETKEY program then sorts this list, 
and writes a new file, called LASTNAME. KEY, which is an alphabetical 
list of LASTNAME fields with their corresponding record numbers. 
(This list is called an “inverted index" in information retrieval 

parlance. ) 

Rename the program shown above as QUERY, and massage it a bit so 
that it reads a sorted key file into memory. The command line might 
appear as: 

QUERY NAMES.DAT LASTNAME. KEY 

Instead of reading a number, the QUERY program reads an alphanumeric 
string which is a particular key to find in the NAMES.DAT data base. 
Since the LASTNAME. KEY list is sorted, you can find a particular entry 
quite rapidly by performing a "binary search," similar to looking up a 
name in the telephone book. That is, starting at both ends of the 
list, you examine the entry halfway in between and, if not matched, 
split either the upper half or the lower half for the next search. 
You'll quickly reach the item you're looking for (in log2(n) steps) 
where you'll find the corresponding record number. Fetch and display 
this record at the console, just as we have done in the program shown 
above. 
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At this point you're just getting started. With a little more 
work, you can allcw a fixed grouping size which differs from the 128 
byte record shown above. This is accomplished by keeping track of the 
record number as well as the byte offset within the record. Knowing 
the group size, you randomly access the record containing the proper 
group, offset to the beginning of the group within the record read 
sequentially until the group size has been exhausted. 

Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy several 
relationships, such as a LASTNAME between HARDY and LAUREL, and an AGE 
less than 45. Display all the records which fit this description. 
Finally, if your lists are getting too big to fit into memory, 
randomly access your key files from the disk as well. One note of 
consolation after all this work: if you make it through the project, 
you'll have no more need for this manual! 
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6 „ SYSTEM FUNCTION SUMMARY 


FUNC 

FUNCTION NAME 

INPUT PARAMETERS 

OUTPUT RESULTS 

3 . 

Systen Reset 

none 

none 

1 

Console Input 

none 

A * char 

2 

Console Output 

E * char 

none 

3 

Reader Input 

none 

A * char 

4 

Punch Output 

E * char 

none 

S 

List Output 

E » char 

none 

6 

Direct Console I/O 

see def 

s ee der 

7 

Get I/O Byte 

none 

A * IOBYTE 

8 

Set I/O Byte 

E * X GBYTE 

none 

9 

Print String 

DE * .Buffer 

none 

1 9 

Read Console Buffer 

DE * .Buffer 

see def 

11 

Get Console Status 

none 

A * 08/FF 

12 

Return Version Number 

none 

HL* version* 

13 

Reset Disk System 

none 

see def 

14 

Select Disk 

E * Disk Number 

see def 

IS 

Open File 

DE * . FCB 

A » Dir Code 

16 

Close File 

DE * . FCB 

A * Dir Code 

17 

Search for First 

DE * . FCB 

A * Dir Code 

13 

Search for Next 

none 

A * Dir Code 

19 

Delete File 

DE * . FCB 

A * Dir Code 

20 

Read Sequential 

DE * . FCB 

A * Err Code 

21 

Write Sequential 

DE * .FCB 

A * Err Code 

22 

Make File 

DE * .FCB 

A * Dir Code 

23 

Rename File 

DE * .FCB 

A * Dir Code 

24 

Return Login Vector 

none 

HL* Login Vect* 

25 

Return Current Disk 

none 

A * Cur Disk-# 

26 

Set DMA Address 

DE * .DMA 

none 

27 

Get Adar (Alloc) 

none 

HL* .Alloc 

28 

Write Protect Disk 

none 

see def 

29 

Get R/O Vector 

none 

HL* R/O Vect* 

30 

Set File Attributes 

DE * .FCB 

see def 

31 

Get Addr(d-isk paras) 

none 

HL* .DFB 

32 

Set/Get User Code 

see def ' 

see def 

33 

Read Rand os 

DE * .FCB 

A * Err Code 

34 

Write Randan 

DE * .FCB 

A * Err Code 

35 

Compute File Size 

DE * .FCB 

r0, cl, r2 

36 

Set Randan Record 

DE » .FCB 

r0 , rl, r2 


* Note that A * L, and 3*3 upon return 


) 
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Copyright 1980 by Vector Graphic Inc. 

All rights reserved. 

Disclaimer 

Vector Graphic makes no representations or warranties with respect to the 
contents of this manual itself, whether or not the product it describes is 
covered by a warranty or repair agreement. Further, Vector Graphic reserves 
the right to revise this publication and to make changes from time to time 
in the content hereof without obligation of Vector Graphic to notify any 
person of such revision or changes, except when an agreement to the contrary 
exists. 


Revisions 

The date and revision of each page herein appears at the bottom of each 
page. The revision letter such as A or B changes if the MANUAL has been 
improved but the PRODUCT itself has not been significantly modified. The 
date and revision on the Title Page corresponds to that of the page most 
recently revised. When the product itself is modified significantly, the 
product will get a new revision number, as shown on the manual's title page, 
and the manual will revert to revision A, as if it were treating a brand new 
product. EACH MANUAL SHOULD CNLY BE USED WITH THE PRODUCT IDENTIFIED ON THE 
TITLE PAGE. 
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I. 


PERSPECTIVE 


1*1 What the MDQS To CP/M File Conversion Program Does 

The MDOS to CP/M File Conversion Program is designed to transfer Assembly 
Language and Basic files from MDOS diskettes to CP/M diskettes. It 
transfers them without changing the inherent value of any program 
statements. The user does, however, have the option of flagging 
non-equivalent Basic command "verbs" so that they will appear in reverse 
video when the file is edited with the SCOPE program editor. 

The program will accept as input any MDOS file whose type is either 04, 06, 
or 10. It will not accept file types 03, 0C or 14, and will bring that to 
the user's attention by a wrong file type message. 

It will then output the file correctly formatted to CP/M specifications. 
The user has the responsibility of naming the new file and declaring its 
type. Generally, it will fall into the .BAS or .ASM catagories. 
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II. 


USER'S GUIDE 


2.1 Purpose of Program 

1. The primary purpose of the Transfer Program is to transfer files from the 
MDOS operating system to the CP/M operating system. The Basic file portion 
of the program transfers files that are Basic program source code only. It 
is intended to transfer from operating system to operating system and is not 
intended to transfer from Micrcpolis Basic to Microsoft Basic. Only those 
generalities and procedures associated with the minimal Basic functions and 
attributes are identical and need not be edited. All special functions and 
extensions peculiar to each Basic are definitely not compatible and need to 
be edited. Some recommendations on transfering Basic source codes are: 

a) Transfer the Basic file flagging the non-equivalent verbs using this 
program. 

b) Edit the file using SCOPE. 

c) Attempt to run the edited program in order to find, discrepancies between 
the two Basics. 


d) Run test data to verify program. 


There are some minor inconsistencies between Micrcpolis Basic and Microsoft 
Basic. An example is in Micrcpolis Basic the statement: 


IF A=10 PRINT "AOK" 


In Microsoft Basic there must be a "then" after the conditional test: 


IF A=10 THEN PRINT "AOK" 

Another example is that Microsoft Version 5 must have spaces between verbs 
and Micropolis doesn't. However, this has been taken care of in the 
transfer program which automatically inserts spaces. 


2.2 How To Transfer MDOS Files To CP/M 


1. Connect all hardware. 

2 . Make sure no disks are mounted. 


3 . 



On the computer, turn the power key on or turn the power switch on, 
whichever applies. 

When the computer has been turned on, a banner will appear on the operator's 
console saying "Vector Graphic Monitor, Version 4.X", and "Mon>" will appear 
on the left edge of the screen. The "Mon>" is the "prompt" telling you the 
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computer's Monitor executive is waiting for a command. If the Monitor 
executive prompt does not appear, depress the reset button on the computer 
chassis. 

5. Insert and mount the personalized Vector Graphic CP/M 2.X System Diskette in 
drive A, label side leftward. 

6. In response to the Monitor prompt "Mon>", depress B on the keyboard. Drive 
A should activate as indicated by its small red lamp. In a moment you will 
see a banner reading "Vector Graphic 56K CP/M - VERSION 2. XX", followed by 
an "A>" in the left-hand edge of the screen. This prompt indicates that the 
CP/M executive is waiting for a command. The CP/M executive is normally 
called the CCP, which stands for Console Command Processor. 

7. Place the diskette you received with the XFER program on it in drive B. 
Transfer the XFER program to your personalized CP/M diskette by typing; 
PIPAs - Bs XFER. COM ( return ) „ Check to make sure the program has been 
transfered by typing DIR in response to the A> prompt. XFER.COM should be 
listed with the other files on your personalized CP/M diskette. When you 
are sure the program has been transfered, store the original diskette in a 
safe place . 

8. In response to Monitor prompt "A>", type XFER ( return ) . Drive A should 
activate as indicated by its small red lamp. In a moment you will see a 
banner reading; 


MDOS to CP/M TRANSFER VERSION 1.0 
Insert MDGS diskette in drive B 
MDQS source filename ; 

9. Insert and mount the MDOS diskette in drive B as indicated in step 5. Type 
in the file you wish transferred following "MDOS source filename" on the 
screen. Press ( return ) . "CP/M destination filename" will now appear at 
the bottom of the screen. 

10. In response to "CP/M destination filename" type the name in the file you 
wish transferred to the CP/M diskette followed by the file extent separated 
by a period. Depress ( return ) . Immediately after depressing the ( return ) 
key, you ‘will note that the small red lan?) indicating drive B will light, 
followed by the red lamp on drive A lighting and going off. 


NOTE 

CP/M WILL CNLY ACCEPT FILENAMES WITH EIGHT LETTERS OR LESS. MDOS ACCEPTS 
FILENAMES WITH UP TO TEN LETTERS. MAKE CERTAIN THAT THE DESTINATION 
FILENAME HAS EIGHT LETTERS OR LESS AND IS FOLLOWED BY THE FILE TYPE. 

11. If you are transferring a Basic program, "Flag non-equivalent verbs (Y/N)" 
will appear at the bottom of the screen. If you prefer to have 
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non-equivalent verbs flagged in the transferred file type Y, if not type N. 
The small red lamps indicating drives A and B will now” alternately light 
back and forth for a few moments. When the lamps stop lighting, the file is 
transfered. You may now view this .BAS file with SCOPE. If you have 
answered "Y" to the question, all non-equivalent "verbs" will stand out in 
reverse video. Be aware that there may be other syntactical differences 
between programs which will have to be changed. 

Seme examples of the differences between Basic programs are shown below. 

a) In Micropolis Basic to open a file: 

OPEN File number 0-9 , String expression for filename , 

[end line number,] [error line number] ’ 

Equivalent statement in Microsoft Basic 

OPEN <Mode>, File number 0-15 , String expression for filenames , [reclen] 

IF EOF ( File name ) then line number 
On error GOTO line number 


b) Writing to a file sequentially 

Given A=10 File 1 has been opened 

B=20 D$=Address 

C$="Name" 

In MEOS: 

Put 1 A; B; ", n +C$ + +D$ 

In Microsoft: 

Write #1,A,B,C$,D$ 


c) Outputting to a port 
Micropolis: 

Out (Numeric expression for port) = data 
Microsoft: 

CXat Port, data 

See the section on Micropolis Basic in the MDOS manual and the Microsoft 
Basic-80 section in the CP/M manual for further details. 
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2. 3 ERROR MESSAGES 

There are four possible error messages in the CP/M File Conversion Program. 
They are: 


****FILE MOT FOUND**** 
****DUPLICATE FILE NAME**** 
****DISK I/O ERROR**** 
****WRCNG FILE TYPE**** 


An explanation of the four error messages will follow: 

1) File Not Found. File name specified in a disk command does not exist on 
the specified diskette. 

2) Explicate File Name. An attempt was made to OPEN a file that already 
exists as a file. 

3) Disk I/O Error. A disk I/O error occurred vfoich was not recoverable in 
the disk I/O retry logic. 

4) Wrong File Type. The attributes of the referenced file are inconsistent 
with the requirements of the statement or command that referenced it. 


2.4 FILE TYPE EXPIANATION 

1. MDOS allows files to be classified as to unique information content by 
assigning a type designation. A files' access codes and type designation 
are combined in one byte of the files' directory entry. The first two least 
significant bits of the file type byte are bit encoded and specify file 
access restrictions. The access codes are as follows: 

Bit 

1 0 

00 A normal read/write file 

0 1 A normal read only file 

10 A permanent read/write file 

11 A permanent read only file 

2. CP/M contains three file types that are part of the system, they are CCM 

(Command) which can be directly executed from the keyboard; BAS (Basic), 
which designates a Basic file; and ASM (Assembler) which designates an 
assembly language file. Other file types can be created by the user to fit 
a particular need. 
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